Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Testing & Debugging/Mac OS Development Toolkit/Automation Essentials 2.3.0/Host Automation Folder/VU External Tool libs/FileToolOperations.Lib

Text File | 1998-03-19 | 20.4 KB | 571 lines | [TEXT/MPS ]

#
# ****************************************************************************
#
#    File Name:    FileToolOperations.Lib
#
#    Contains:    Tasks which extend the basic functionality of the FileTool.vulib.
#
#    Written by:    KTA
#
#    Copyright:    © 1993-1997 by Apple Computer, Inc., all rights reserved.
#
# ****************************************************************************
#            C h a n g e        H i s t o r y (most recent first):
# ****************************************************************************
#
#        Vers      Date        Author        Description
#        ----    --------    ------    ---------------------------------------------
#        2.2.2    2/12/97        JAS        Added 'vers' resources to library.
#                                    These should always match tool version when tool is revved.
#        <15>     2/23/96    JC        Add TRACS support.
#        <14>     4/25/95    KTA        ExistsOrCreate() - Fixed bug where returnVal was being set
#                                    incorrectly.
#        <13>     2/16/95    KTA        _FileTool() - Replaced with standard new version of standard
#                                    template which fixes some problems.
#        <12>     1/31/95    KTA        Changed pOntarget parameter to true in many tasks.
#        <11>     1/19/95    KTA        Changed the name of ExceptionHandler() to ExceptionDispatcher().
#        <10>     1/13/95    KTA        _FileTool() - Added support for calling tasks as well as
#                                    services.
#         <9>      1/6/95    KTA        QuitFileTool() - created.
#         <8>    12/12/94    KTA        _FileTool() - Changed match[target] to match[mouse];
#         <7>    12/12/94    KTA        _FileTool() - Only match the target if pOnTarget is true
#         <6>    12/12/94    KTA        Added task _FileTool for exceptionHandling, and updated tasks to
#                                    call it.
#         <5>     4/11/94    KTA        Updated library dependancy list.
#         <4>     4/11/94    KTA        Added several new tasks
#         <3>      4/7/94    KTA        ExistsOrCreate() - Support creation of folders.
#         <2>      4/1/94    KTA        InitFileTool() -  gFileToolStatus, removed println.
#         <1>     3/28/94    KTA        Created - first checked in.
#
# ****************************************************************************
#

########################################################################
#                            External libraries
#=======================================================================
Libraries "FileTool.vuLib", "FileToolHost.vuLib", "Output.Lib", "String.Lib", "ExceptionHandling.Lib";

#########################################################################
#        _FileTool(pOnTarget := true)
#========================================================================
# Author:        KTA
# Description:    Does the exception handling for the Filetool.  All high level tasks
#                should call this routine for file tool services or tasks within the
#                FileTool.vulib.  Handles initialization of tool automatically.
# Parameters:    pServiceorTask - Name of the Service or task
#                pParamList - List of parameters
#                pOnTarget - Flag to indicate whether the service should be performed
#                            the host or the target.  1 = target/0 = host.
# Returns:        What ever the file tool returns - list of three elements
#                            { errCode, Data, [error message]}
# Examples:        _FileTool('ReadUntil', {'HD:FileName'},1);
# Assumptions:    None
#========================================================================
# History:
# KTA    12/12/94    Only match the mouse if pOnTarget is true
# KTA    1/13/95        Added support for calling tasks as well as services
# KTA    2/16/95        coerce pOnTarget to be either true or false, Temporarily
#                    turn commandexceptions off, check scripterror, reset
#                    commandexceptions, and if necessary throw scripterror
#  JC    2/19/96        Updated to support FiletToolHost calls from the "FileToolHost.vuLib"
#                    lib. This was done to support TRACS output support.
#########################################################################
TASK _FileTool(pServiceOrTask, pParamList := {}, pOnTarget := true, pIsRetry := 0)
begin
    Try
    begin
        returnVal := undefined;
        ParamType := TypeOf(pServiceOrTask);

        if (ParamType = 'string') # Service Call
        begin
            if (pOnTarget)
                pOnTarget := true;
            else
                pOnTarget := false;
            if not(global gFileToolInitFlag = pOnTarget)
            begin
                try
                begin
                    temp := CommandExceptions(0);
                    if (pOnTarget)
                        FileToolInit :=  FileTool("Initialize", pOnTarget );         # initialize FileTool
                    else
                        FileToolInit :=  FileToolHost("Initialize", pOnTarget );         # initialize FileTool
                    InitError := Scripterror();
                    CommandExceptions(temp);
                    if (FileToolInit[1] <> 0)        # If error
                    begin
                        println "FileTool error ( ", FileToolInit[1], ", ",  FileToolInit[3] , " )";
                        gFileToolInitFlag := undefined;
                        if (CommandExceptions())
                            throw InitError;
                        return(FileToolInit);
                    end;
                    else
                        gFileToolInitFlag := pOnTarget;
                end;
                catch theErr
                begin
                    ExceptionDispatcher(theErr);
                    return(FileToolInit);
                end;
            end;

            try
            begin
                NumParams := Card(pParamList);
                if (pOnTarget)
                begin
                    switch NumParams
                    begin
                        case 0:                    # 0 parameters
                            returnVal := FileTool(pServiceOrTask);
                        case 1:                    # 1 parameter
                            returnVal := FileTool(pServiceOrTask, pParamList[1]);
                        case 2:                    # 2 parameters
                            returnVal := FileTool(pServiceOrTask, pParamList[1], pParamList[2]);
                        case 3:                    # 3 parameters
                            returnVal := FileTool(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3]);
                        case 4:                    # 4 parameters
                            returnVal := FileTool(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4]);
                        case 5:                    # 5 parameters
                            returnVal := FileTool(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5]);
                        case 6:                    # 6 parameters
                            returnVal := FileTool(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5], pParamList[6]);
                        default:                # error
                            println "Error - unsupported number of parameters - {NumParams}";
                    end;
                end;
                else
                begin
                    switch NumParams
                    begin
                        case 0:                    # 0 parameters
                            returnVal := FileToolHost(pServiceOrTask);
                        case 1:                    # 1 parameter
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1]);
                        case 2:                    # 2 parameters
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1], pParamList[2]);
                        case 3:                    # 3 parameters
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3]);
                        case 4:                    # 4 parameters
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4]);
                        case 5:                    # 5 parameters
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5]);
                        case 6:                    # 6 parameters
                            returnVal := FileToolHost(pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5], pParamList[6]);
                        default:                # error
                            println "Error - unsupported number of parameters - {NumParams}";
                    end;
                end;

                if (returnVal[1] <> 0)        # If error
                begin
                    if(returnVal[1] = -1) and not (pIsRetry)    # Not initialized, and haven't retried already
                    begin
                        global gFileToolInitFlag := undefined;
                        returnVal := _FileTool(pServiceOrTask, pParamList, pOnTarget, 1);
                    end;
                end;
                else if(pServiceOrTask = 'Quit')        # Reset the global gFileToolInitFlag when we quit
                    global gFileToolInitFlag := undefined;

            end;
            catch theErr
            begin
                if(theErr = -1220) and not (pIsRetry)
                begin
                    global gFileToolInitFlag := undefined;
                    returnVal := _FileTool(pServiceOrTask, pParamList, pOnTarget, 1);
                end;
                else
                    exceptionDispatcher(theErr);
                end;
            end;
            else if(ParamType = 'task')
            begin
                NumParams := Card(pParamList);
            switch NumParams
            begin
                case 0:                    # 0 parameters
                    returnVal := call (pServiceOrTask);
                case 1:                    # 1 parameter
                    returnVal := call (pServiceOrTask, pParamList[1]);
                case 2:                    # 2 parameters
                    returnVal := call (pServiceOrTask, pParamList[1], pParamList[2]);
                case 3:                    # 3 parameters
                    returnVal := call (pServiceOrTask, pParamList[1], pParamList[2], pParamList[3]);
                case 4:                    # 4 parameters
                    returnVal := call (pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4]);
                case 5:                    # 5 parameters
                    returnVal := call (pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5]);
                case 6:                    # 6 parameters
                    returnVal := call (pServiceOrTask, pParamList[1], pParamList[2], pParamList[3], pParamList[4], pParamList[5], pParamList[6]);
                default:                # error
                    println "Error - unsupported number of parameters - {NumParams}";
            end;
        end;

        if(pOnTarget)            # To cause target errors to throw if Xtools are called
            match[mouse];

        return(returnVal);
    end;
    Catch theError
        ExceptionDispatcher(theError);
end;

#########################################################################
#        InitFileTool(pOnTarget := true)
#========================================================================
# Author:        KTA
# Description:    Initializes the FileTool
# Parameters:    pOnTarget - True if you want to launch the FileTool on
#                                the target machine. False if on the Host.
# Returns:        0 - Couldn't initialize
#                1 - Init On Target
#                2 - Init On Host
# Examples:        InitFileTool();
# Assumptions:    None
#========================================================================
# History:
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK InitFileTool(pOnTarget := true)
begin
    returnVal := 0;
    FileToolInit :=  _FileTool( "Initialize", {pOnTarget}, pOnTarget);         # Launch FileTool
    if FileToolInit[1] <> 0                                    # If error during initialization,
    begin
        println "FileTool could not be initialized";        # print error
        println "Error ", FileToolInit[1], ". ",  FileToolInit[3] ;
    end;
    else
    begin
        if (pOnTarget)        # Was it on the Target
            returnVal := 1;
        else                     # Or was it on the Host
            returnVal := 2;

    end;
    return(returnVal);
end;
#########################################################################
#        QuitFileTool()
#========================================================================
# Author:        KTA
# Description:    Quits the FileTool
# Parameters:    none
# Returns:        0 - Couldn't Quit
#                1 - Quit Successfully
# Examples:        QuitFileTool();
# Assumptions:    None
#========================================================================
# History:
# KTA    1/6/95    Created
#########################################################################
TASK QuitFileTool(pOnTarget := true)
begin
    FileToolQuit :=  _FileTool( "Quit", ,pOnTarget);         # Quit FileTool
    if (FileToolQuit[1] <> 0)                                    # If error during initialization,
    begin
        println "FileTool could not be quit";        # print error
        println "Error ", FileToolQuit[1], ". ",  FileToolQuit[3] ;
        returnVal := 0;    # Error
    end;
    else
        returnVal := 1;    # Success
    return(returnVal);
end;


#########################################################################
#        ReadTheLine( pFileReference, pFromPosition, pOnTarget )
#========================================================================
# Author:        KTA
# Description:    Similar to ReadLine in ?FileTool.vulib except this routine does the error
#                checking and will return 0 if an error occur otherwise it will
#                what the line that was read (2nd element of what theFileTool returned)
# Parameters:    pFileReference - File to read from.
#                pFromPosition - position to begin reading from.
# Returns:        0 - Some Error
#                String - line read
# Examples:        ReadTheLine('hd:myFile', 0);
# Assumptions:    None
#========================================================================
# History:
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
task ReadTheLine( pFileReference, pFromPosition := 0, pOnTarget := true )
begin
    theLine := _Filetool('ReadUntil', {pFileReference, 0, "∂n", pFromPosition}, pOnTarget );
    if(theLine[1] <> 0)
    begin
        println "Problem reading the file";        # print error
        println "Error ", theLine[1], ". ",  theLine[3] ;
        returnVal := undefined;
    end;
    else
        returnVal := theLine[2];
    return (returnVal);
end;


#########################################################################
#                        ExistsOrCreate(pFileName, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Checks to see if the <pFileName> exists - creates one if it does not.
# Parameters:    pFileName - full path of file
# Returns:        0 - Fail (doesn't exist, couldn't create)
#                1 - File Existed
#                2 - Created File
#                3 - Created Folder
# Examples:        ExistsOrCreate();
# Assumptions:    None
#========================================================================
# History:
# KTA    4/7/94    Support creation of folders
# KTA    12/12/94    Updated to call _FileTool()
# KTA    4/25/95        Fixed bug where returnVal was being set incorrectly
#########################################################################
task ExistsOrCreate(pFileName, pOnTarget := true )
begin
    returnVal := 0;
    ###    Create the file only if it doesn't exist
    x := _FileTool( "FileExists", {pFileName}, pOnTarget);
    if not (TypeOf( x ) = 'list' and x[1] = 0)
    begin
        strLen := Card(pFileName);
        if( pFileName[strLen] = ':')
        begin
            CreatedFolder := _FileTool( "CreateFolder", {pFileName} , pOnTarget);
            If(CreatedFolder[1] = 0)    # Folder was created
                returnVal := 3;
            else
            begin
                Println "!@#$% An error occured while creating the file";
                Println "Error", CreatedFolder[1], CreatedFolder[3];
            end;
        end;
        else
        begin
            ###    Create the File
            CreatedFile := _FileTool( "Create", {pFileName,'MPS ', 'TEXT'}, pOnTarget );
            If(CreatedFile[1] = 0)    # File was created
                returnVal := 2;
            else
            begin
                Println "!@#$% An error occured while creating the file";
                Println "Error", CreatedFile[1], CreatedFile[3];
            end;
        end;
    end;
    else        # File must Exist
        returnVal := 1;

    return(returnVal);
end;


#########################################################################
#                MoveTheFile(pSourcePath, pDestinationPath, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Moves Files from <pSourcePath> to <pDestinationPath>
#
# Parameters:    pSourcePath - (String) Fullpath location of file to be moved. Should
#                            be in the form: "HD:Folder:FileName".
#                pDestinationPath - (String) Fullpath location where file should be
#                                moved to. Should be in the form: "HD:Folder:FileName2" where
#                                FileName2 is the new name for the file.
#
# Returns:        0 - error occured
#                integer - file reference for file moved.
# Assumptions:     File exists in <pSourcePath> and <pDestinationPath> is a valid path.
#                This routine does not check to see if either exist nor does it
#                return errors if either is not found.
#========================================================================
# History:
# KTA    3/29/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK MoveTheFile(pSourcePath, pDestinationPath, pOnTarget := true )
begin
    theMove := _FileTool( "Move", {pSourcePath,0,pDestinationPath}, pOnTarget);
    if(theMove[1] <> 0)
    begin
        println "Problem moving the file";        # print error
        println "Error ", theMove[1], ". ",  theMove[3] ;
        returnVal := 0;
    end;
    else
    begin
        returnVal := theMove[2];
        LogStr("Moving the file '{pSourcePath}' to '{pDestinationPath}'");
    end;
    return (returnVal);
end;

#########################################################################
#                        DoesFileExist(pFilePath, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    This task checks to see if the file <pFilePath> exists.
# Parameters:    pFilePath - full path to a file.
# Returns:        0 - File does not exist.
#                1 - file exists
#========================================================================
# History:
# KTA    1/6/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK DoesFileExist(pFilePath := "", pOnTarget := true)
begin
    returnVal := 0;
    x :=  _FileTool( "FileExists", {pFilePath},pOnTarget);
    if(x[1] = -43)
    begin
        #println  "The file '{pFilePath}' does not exist";
    end;
    else if(x[1] <> 0)
        println "Error: ", x[1], "    ", x[3];
    else if (x[2])
    begin
        #println "The file '{pFilePath}' exists";
        returnVal :=1;
    end;

    return(returnVal);
end;

#########################################################################
#                        PathToSpecialFolder(pSpecialFolder, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Returns the path to the special folder.
# Parameters:    None
# Returns:        0 - error occured
#                string - full path to system folder in following format:
#                "hd:Systemfolder"
#    x := PathToSpecialFolder("extn" );
#    x := PathToSpecialFolder("ctrl" );
#    x := PathToSpecialFolder("macs" );
#========================================================================
# History:
# KTA    1/6/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK PathToSpecialFolder(pSpecialFolder := '', pOnTarget := true)
begin

    x := _FileTool( "FindFolder", {pSpecialFolder}, pOnTarget);
    if(x[1] <>0)
    begin
        println "Error: ", x[1], "    ", x[3];
        return(0);
    end;
    else
        return(x[2]);
end;

#########################################################################
#                        NameOfBootVolume(pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Returns the name of the boot volume
# Parameters:    None
# Returns:        0 - error occured
#                string - Name of the boot volume
#========================================================================
# History:
# KTA    1/6/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK NameOfBootVolume(pOnTarget := true)
begin
    x := _FileTool( "VolumeList", ,pOnTarget);
    if(x[1] <>0)
    begin
        println "Error: ", x[1], "    ", x[3];
        return(0);
    end;
    else
        return(x[2][1]);
end;

#########################################################################
#                        DeleteTheFile(pFileName, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Deletes the file <pFileName>
# Parameters:    pFileName - full path to the file to be deleted.
# Returns:        0 - error occured
#                1 - file was deleted properly
#========================================================================
# History:
# KTA    1/6/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK DeleteTheFile(pFileName, pOnTarget := true)
begin
    x :=  _FileTool( "Delete", {pFileName,0},pOnTarget);
    if(x[1] <>0)
    begin
        println "Error: ", x[1], "    ", x[3];
        return(0);
    end;
    else
    begin
        Println "Deleted file '{pFileName}'";
        return(1);
    end;
end;


#########################################################################
#                CopyFileToPath(pFileToCopy,pDestinationPath, pOnTarget)
#========================================================================
# Author:        KTA
# Description:    Copies the file <pFileToCopy> to the directory specified by
#                the input parameter <pDestinationPath>.
#                Folder. This must be the full path of the file not just the filename.
# Parameters:    pFileToCopy - Full path to source file in the form: "hd:fileName"
# Returns:        0 - error occured
#                1 - file was copied properly
#========================================================================
# History:
# KTA    3/29/94    created
# KTA    12/12/94    Updated to call _FileTool()
#########################################################################
TASK CopyFileToPath(pFileToCopy := '', pDestinationPath := 'SystemFolder', pOnTarget := true)
begin
    returnVal := 0;
    if(pFileToCopy)
    begin
        if (pDestinationPath = 'SystemFolder')
            pDestinationPath := PathToSpecialFolder('macs');

        ExistsFlag := DoesFileExist(pFileToCopy);
        if(ExistsFlag)
        begin
            n := NumTimesCharInString(pFileToCopy, ':');
            theFile := StringAfterChar(pFileToCopy, ':',0,n);
            x := _FileTool( "CopyFile",{pFileToCopy, 0,"{pDestinationPath}{theFile}"}, pOnTarget );
            if(x[1] <>0)
            begin
                println "Error: ", x[1], "    ", x[3];
            end;
            else
            begin
                println "Copied '{pFileToCopy}' to '{pDestinationPath}'";
                returnVal := 1;
            end;
        end;
    end;
    else
        println "The file to copy was not specified";

    return(returnVal);
end;